/**
 The MIT License

Copyright (c) <2011> <JPACHUBE Team>

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
 */
package com.pachube.api;

import java.awt.Color;

import com.pachube.exceptions.PachubeException;
import com.pachube.http.client.HttpResponse;

/**
 * The Interface Pachube.
 */
public interface Pachube {

    /**
     * Gets a Feed by Feed ID.
     * 
     * @param feed Id of the Pachube feed to retrieve
     * @return Feed which corresponds to the id provided as the parameter
     * @throws PachubeException If something goes wrong.
     */
    public Feed getFeed(int feed) throws PachubeException;

    /**
     * Creates a new feed from the feed provide. The feed provide should have no
     * ID, and after this method is called is usless, to make chanegs to the new
     * feed methods should be invoked on the return object.
     * 
     * @param f Feed to create, This Feed Should have no ID field and atleast
     *            should have its title field filled in. This feed is not 'live'
     *            any attempt to change this object will be ignored.
     * @return Representation of the feed from pachube, this is a 'live' Feed
     *         and method can invoked which will change the state of the online
     *         feed.
     * @throws PachubeException If something goes wrong.
     */
    public Feed createFeed(Feed f) throws PachubeException;

    /**
     * This Method is not intended to be used by Users, instead get the Feed
     * object using getFeed() and update the Feed from there, All changes will
     * be made to the online Feed.
     * 
     * @param feed the feed
     * @param s the s
     * @return true, if successful
     * @throws PachubeException the pachube exception
     */
    public boolean updateFeed(int feed, String s) throws PachubeException;

    /**
     * Delete a Feed specified by the feed id. If any Feed object exists that is
     * a representation of the item to be deleted, they will no longer work and
     * will throw errors if method are invoked on them.
     * 
     * @param feed If of the feed to delete
     * @return HttpResponse
     */
    public HttpResponse deleteFeed(int feed);

    /**
     * This Method is not intended to be used by Users, instead get the Feed
     * object using getFeed() and create Datastreams from there, All changes
     * will be made to the online Feed.
     * 
     * @param feed the feed
     * @param s the s
     * @return true, if successful
     * @throws PachubeException the pachube exception
     */
    public boolean createDatastream(int feed, String s) throws PachubeException;

    /**
     * This Method is not intended to be used by Users, instead get the Feed
     * object using getFeed() and delete Datastreams from there, All changes
     * will be made to the online Feed.
     * 
     * @param feed the feed
     * @param datastream the datastream
     * @return the http response
     */
    public HttpResponse deleteDatastream(int feed, int datastream);

    /**
     * This Method is not intended to be used by Users, instead get the Feed
     * object using getFeed() and update Datastreams from there, All changes
     * will be made to the online Feed.
     * 
     * @param feed the feed
     * @param datastream the datastream
     * @param s the s
     * @return the http response
     */
    public HttpResponse updateDatastream(int feed, int datastream, String s);

    /**
     * This Method is not intended to be used by Users, instead get the Feed
     * object using getFeed() and get Datastreams from there.
     * 
     * @param feed the feed
     * @param datastream the datastream
     * @return the datastream
     */
    public HttpResponse getDatastream(int feed, int datastream);

    /**
     * This Method is not intended to be used by Users, instead get the Feed
     * object using getFeed() and access Datastream history from there.
     * 
     * @param feed the feed
     * @param datastream the datastream
     * @return the datastream history
     */
    public Double[] getDatastreamHistory(int feed, int datastream);

    /**
     * This Method is not intended to be used by Users, instead get the Feed
     * object using getFeed() and access Datastream archive from there.
     * 
     * @param feed the feed
     * @param datastream the datastream
     * @return the datastream archive
     */
    public String[] getDatastreamArchive(int feed, int datastream);

    /**
     * Creates a Trigger on pachube from the object provided.
     * 
     * @param t the t
     * @return the string
     * @throws PachubeException the pachube exception
     */
    public String createTrigger(Trigger t) throws PachubeException;

    /**
     * Gets a Trigger from pachube specified by the parameter.
     * 
     * @param id id of the Trigger to get
     * @return the trigger
     * @throws PachubeException the pachube exception
     */
    public Trigger getTrigger(int id) throws PachubeException;

    /**
     * Gets all the Triggers owned by the authenticating user.
     * 
     * @return the triggers
     * @throws PachubeException the pachube exception
     */
    public Trigger[] getTriggers() throws PachubeException;

    /**
     * Deletes a Trigger from pachube.
     * 
     * @param id id of the trigger to delete
     * @return the http response
     */
    public HttpResponse deleteTrigger(int id);

    /**
     * Updates a Trigger on pachube.
     * 
     * @param id id of the triggerto update
     * @param t Trigger object of the new trigger
     * @return the http response
     */
    public HttpResponse updateTrigger(int id, Trigger t);

    /**
     * Gets a Pachube graph of the datastream.
     * 
     * @param feedID ID of feed the datastream belongs to.
     * @param streamID ID of the stream to graph
     * @param width Width of the image
     * @param height Height of the image
     * @param c Color of the line
     * @return String which can be used to form a URL Object.
     */
    public String showGraph(int feedID, int streamID, int width, int height,
            Color c);

}